home *** CD-ROM | disk | FTP | other *** search
/ Online Today 2000 January / Onto0100.iso / mac / MACAST 1.0 / MACAST Documentation / Plugin Development / MACAST_BLR.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-09-16  |  12.3 KB  |  336 lines  |  [TEXT/CWIE]
  1. /*
  2.     Base Layer Renderer Plug-in API
  3.     ⌐1999, @soft
  4.     
  5.     Description:    The plugin API for MACAST base layer renderer plugins (embedded plugins).
  6.     Version:        1.2
  7.     Released:        9/16/99
  8.     Compatibility:    MACAST 1.0
  9.     Version history:
  10.     
  11.      Date    Who        Changes
  12.     ------+------+------------------------------------------------------
  13.     091699    SKA        Added an ability for alternate BLR displays. See
  14.                     example BLR for usage instructions.
  15.     082399    SKA        Added BLRSettings and BLRListen, and Broadcast
  16.                     callback. All BLRs should be recompiled. 
  17.     071599    SKA        Added BLRKeyDown call and removed BLRIdle (you can
  18.                     do idle processing inside BLRRender).
  19.     071199    SKA        Changed a couple of calls, and commented MACAST call-
  20.                     backs a little better.
  21.     061999    SKA        Added GetSoundBuffer hook for direct access to sound
  22.                     data
  23.     050199    SKA        Added hooks for saving and reading plugin-specific
  24.                     preferences (see maBLRSavePrefs hook)
  25.     042799    SKA        Modified the API with developer suggestions.
  26.     042699    SKA        Initial release
  27.     041299  SKA        Started the work
  28.     
  29.     SKA = Slava Karpenko
  30. */
  31.  
  32. #pragma once
  33. #ifdef __cplusplus
  34. extern "C" {
  35. #endif
  36.  
  37. /************************************************************
  38.                     ENUMS AND CONSTANTS
  39. ************************************************************/
  40. #define BLR_API_VERSION                0x0110
  41. #define plugBaseLayerRenderer        FOUR_CHAR_CODE('BLR!')
  42.  
  43. /************************************************************
  44.                     ERRORS & RETURN VALUES
  45. ************************************************************/
  46. enum {
  47.     // Plugin return codes
  48.     errBLRNoErr            = noErr,
  49.     errBLRTerminate    = 666,            // terminate the plugin
  50.     errBLRNoMemory,                    // terminate the plugin and display no memory alert
  51.     
  52.     errBLRCustom                    // MACAST will call BLRError function and terminate your
  53.                                     //  plugin if you request to.
  54. };
  55.  
  56. /************************************************************
  57.                     FUNCTION DEFINITIONS
  58. ************************************************************/
  59. // Called when the plugin is initialized. You get the FSSpec to the plugin file
  60. // (for opening resfork if you need to), and base layer size.
  61. extern OSStatus    BLRInitialize(FSSpecPtr inPlugin, Rect inRect, UInt32* ioRefcon);
  62.  
  63. // Called on termination. Plugin should dispose all buffers/structures it had and prepare
  64. // the mind for ethernity.
  65. extern OSStatus    BLRTerminate(UInt32* ioRefcon);
  66.  
  67. // Called whenever user presses a key. Your BLR get this event all the time. You can process it or
  68. // ignore it.
  69. extern OSStatus    BLRKeyDown(EventRecord* inEvent, UInt32* ioRefcon);
  70.  
  71. // Return copyrights strings to be displayed on plugin about. \r is acceptable, 3 lines max.
  72. extern OSStatus    BLRGetCopyright(StringPtr outCopyright, UInt32* ioRefcon);
  73.  
  74. // Main function, called periodically -- render base layer. You can use MA callbacks
  75. // to obtain any necessary information.
  76. // Note that inRect is most likely the same as given to you at init time. If user changes
  77. // skin with different computer bounds, MACAST will terminate and re-init the plugin.
  78. extern OSStatus BLRRender(GWorldPtr inRenderTarget, Rect inRect, UInt32* ioRefcon);
  79.  
  80. // This function is called when user clicks in layer that is controlled by your plugin.
  81. // You should look at it and return either 'true' -- means you handled the click and
  82. // MACAST should take no other actions. If you don't handle clicks or don't handle click
  83. // in that point, return false and MACAST will rotate through BLR plugins. inClick is in
  84. // local coordinates relative to inRect given at init time.
  85. extern Boolean BLRClick(Point inClick, UInt32* ioRefcon);
  86.  
  87. // This function called if you return errBLRCustom. You should copy the error string
  88. // and errNum (optionally) and return whether the error is fatal or not. If this function
  89. // returns true, MACAST terminates your plugin, otherwise continues execution.
  90. extern Boolean BLRError(StringPtr outErrString, OSStatus* outErrNum);
  91.  
  92. // If you define this function in your gPlugInfo, MACAST will add a corresponding item into
  93. // 'Settings' submenu of plugins menu and will call this function when user chooses it.
  94. // You can display settings dialog, and do whatever you want.
  95. extern OSStatus BLRSettings(UInt32* ioRefcon);
  96.  
  97. // If you define this in your gPlugInfo, MACAST will send you all internal messages defined in
  98. // MACAST_Events.h. This area is highly undocumented, so it's suggested that if you listen to events
  99. // for some purpose, avoid translating them via Broadcast hook.
  100. extern OSStatus BLRListen(SInt32 inMessage, void* inData, UInt32* ioRefcon);
  101.  
  102. // If your BLR has more than one display mode, it is advisable to return total number of display
  103. // modes here thus allowing users to switch between them via 'Switch Mode' drawer button. Call
  104. // ma->GetMode() in BLRRender to find out in what mode we currently is.
  105. // If you do not define BLRGetModes, MACAST assumes BLR has only one mode.
  106. extern SInt16 BLRGetModes(void);
  107.  
  108. // If your BLR has more than one display mode, this function will be called when user switches modes --
  109. // in attempt to get a mode 'name' to be displayed. if you don't want to display a name for current mode
  110. // return empty string for outName. If you don't want to display a name for all modes, don't define this
  111. // function.
  112. extern OSStatus BLRGetModeName(SInt16 inMode, StringPtr outName);
  113.  
  114. /************************************************************
  115.                     TYPEDEFS AND STRUCTS
  116. ************************************************************/
  117. // ÑPlugin callbacks
  118. typedef OSStatus    (*blrInitProcPtr)(FSSpecPtr, Rect, UInt32*);
  119. typedef OSStatus    (*blrGenericProcPtr)(UInt32*);
  120. typedef OSStatus    (*blrKeyDownProcPtr)(EventRecord*, UInt32*);
  121. typedef OSStatus    (*blrGetCopyrightProcPtr)(StringPtr, UInt32*);
  122. typedef OSStatus    (*blrRenderProcPtr)(GWorldPtr, Rect, UInt32*);
  123. typedef Boolean        (*blrClickProcPtr)(Point, UInt32*);
  124. typedef Boolean     (*blrErrorProcPtr)(StringPtr, OSStatus*);
  125. typedef OSStatus    (*blrListenProcPtr)(SInt32, void*, UInt32*);
  126. typedef SInt16        (*blrGetModesProcPtr)(void);
  127. typedef OSStatus     (*blrGetModeNameProcPtr)(SInt16 inMode, StringPtr outName);
  128.  
  129. // ÑMACAST Callbacks
  130. //  You heavily rely on these to deliver good rendering.
  131.  
  132. typedef void        (*maBLRGetValuesArray)(UInt8** outArray, UInt16* outArraySize);
  133. // Get an array of pre-computed values for frequences.
  134. // Every value represents one frequency, and can be in range #0-232.
  135. // Input:
  136. //        none
  137. //    Output:
  138. //        outArray        = pointer to values array
  139. //        outArraySize    = size of the array
  140. //    Returns:
  141. //        nothing
  142.  
  143. typedef void        (*maBLRGetFFTArray)(double** outFFT, UInt16* outFFTSize);
  144. // Get FFT array. First half of the array are real parts, second - imaginary.
  145. // Input:
  146. //        none
  147. //    Output:
  148. //        outFFT            = pointer to raw fft array (or nil, if not available)
  149. //        outBufferSize    = size of the array
  150. //    Returns:
  151. //        nothing
  152.  
  153. typedef void        (*maBLRGetSoundBuffer)(Ptr* outSoundBuffer, UInt16* outBufferSize);
  154. // Get current sound buffer.
  155. // Input:
  156. //        none
  157. //    Output:
  158. //        outSoundBuffer    = pointer to sound buffer being played (or nil, if no track is playing)
  159. //        outBufferSize    = size of the buffer, in bytes
  160. //    Returns:
  161. //        nothing
  162.  
  163. typedef void        (*maBLRGetStatus)(UInt32* outTimer, UInt32* outStatus);
  164. // Get status of thge player (timer, states of repeat, random, sleep etc).
  165. // Input:
  166. //        none
  167. //    Output:
  168. //        outTimer            = timer, in seconds
  169. //        outStatus            = flags field containing stat* constants.
  170. //                                (for example, to check if Random mode is set, check for (outStatus & statRandom))
  171. //    Returns:
  172. //        nothing
  173.  
  174. // Status codes
  175. enum {
  176.     statRandom    = (1L << 0),
  177.     statSleep    = (1L << 1),
  178.     statRepeat    = (1L << 2),
  179.     statRepeat1    = (1L << 3),
  180.     statPlaying = (1L << 4),
  181.     statPaused    = (1L << 5),
  182.     statStopped = (1L << 6)
  183. };
  184.  
  185. typedef void        (*maBLRGetGWorld)(GWorldPtr* outGWorld, Rect* outRect);
  186. // Get a GWorld with digits or status lights.
  187. // Input:
  188. //        none
  189. //    Output:
  190. //        outGWorld            = pointer to a GWorld containing requested data
  191. //        outRect                = rectange defining bounds of GWorld
  192. //    Returns:
  193. //        nothing
  194.  
  195. typedef void        (*maBLRDarkenWorkArea)(void);
  196. // Darken work area (to simulate 'something-on-top' effect).
  197. // Input:
  198. //        none
  199. //    Output:
  200. //        none
  201. //    Returns:
  202. //        nothing
  203.  
  204. typedef void        (*maBLRSetStdColors)(void);
  205. // Set skin-defined colors on current port.
  206. // It's your responsibility to return original colors later.
  207. // Input:
  208. //        none
  209. //    Output:
  210. //        none
  211. //    Returns:
  212. //        nothing
  213.  
  214. typedef OSStatus (*maBLRSavePrefs)(OSType inAuthorID, OSType inPluginID, Ptr inBuffer, UInt16 inSize);
  215. // Save plugin-specific preferences in MACAST Data file located in System Folder.
  216. // Input:
  217. //        inAuthorID         = authorID of plugin
  218. //        inPluginID         = pluginID of plugin
  219. //        inBuffer        = pointer to buffer containing preferences chunk to be saved
  220. //        inSize            = size of buffer to be saved
  221. //    Output:
  222. //        none
  223. //    Returns:
  224. //        noErr            = preferences saved successfully.
  225. //        memFullErr        = an unknown, probably memory-related error has occurred.
  226.  
  227. typedef OSStatus (*maBLRReadPrefs)(OSType inAuthorID, OSType inPluginID, Ptr inBuffer, UInt16* ioSize);
  228. // Read plugin-specific preferences you have saved before with SavePrefs hook.
  229. // Input:
  230. //        inAuthorID         = authorID of plugin
  231. //        inPluginID         = pluginID of plugin
  232. //        inBuffer        = pointer to pre-allocated buffer to store preferences
  233. //        ioSize            = size of allocated buffer
  234. //    Output:
  235. //        ioSize            = actual size of preferences
  236. //    Returns:
  237. //        noErr            = preferences read successfully.
  238. //        resNotFound        = unable to find such preferences chunk
  239. //        memFullErr        = size of preferences chunk exceeds size of allocated buffer
  240. //                            (ioSize contains size of preferences chunk)
  241.  
  242. typedef void (*maBLRBroadcast)(SInt32 inMessage, void* inData);
  243. // Broadcast MACAST system message to its subsystems. Don't call this unless you know
  244. // what you're doing.
  245. // Input:
  246. //        inMessage         = message id to be broadcasted
  247. //        inData             = data to be broadcasted, or nil
  248. //    Output:
  249. //        none
  250. //    Returns:
  251. //        nothing
  252.  
  253. typedef SInt16 (*maBLRGetMode)(void);
  254. // Returns the current mode the MACAST is in. This value is between 0 and numModes-1 returned from
  255. // BLRGetModes call, or always 0 if you have not defined BLRGetModes.
  256. // Input:
  257. //        none
  258. //    Output:
  259. //        none
  260. //    Returns:
  261. //        SInt16            = current mode number (0 <= x <= numModes-1)
  262.  
  263. // Various structures
  264. #pragma options align=power
  265.  
  266. // This is the structure for MACAST callbacks.
  267. typedef struct {
  268.     // Getters
  269.     maBLRGetValuesArray        GetValues;
  270.     maBLRGetFFTArray        GetFFT;
  271.     maBLRGetStatus            GetStatus;
  272.     
  273.     // Utility functions
  274.     maBLRDarkenWorkArea        DarkenWorkArea;
  275.     maBLRSetStdColors        SetStdColors;
  276.     maBLRGetGWorld            GetTimerDigits;
  277.     maBLRGetGWorld            GetStatusLights;
  278.     
  279.     // Preferences
  280.     maBLRSavePrefs            SavePrefs;
  281.     maBLRReadPrefs            ReadPrefs;
  282.     
  283.     maBLRGetSoundBuffer        GetSoundBuffer;
  284.     
  285.     // New for 1.1
  286.     maBLRBroadcast            Broadcast;
  287.     
  288.     // New for 1.2
  289.     maBLRGetMode            GetMode;
  290. } BLRCallbacks, *BLRCallbacksPtr;
  291.  
  292. // Main structure for the plugin. Main entry point for the PEF fragment should point to
  293. // a global variable of this type.
  294. typedef struct {
  295.     UInt16    api;                    // API used. Should always contain BLR_API_VERSION
  296.     OSType    type;                    // Plugin type. Should be plugBaseLayerRenderer.
  297.     
  298.     OSType    authorID;                // Author ID should be registered with @soft to prevent
  299.                                     //  incompatibilities. mailto:devsupport@at-soft.net
  300.     OSType    pluginID;                // Plugin ID can be anything the author wishes. It is
  301.                                     //  used among with author id to store user preferred
  302.                                     //  base layer renderer plugin etc.
  303.     
  304.     UInt32    flags;                    // Plugin flags    (reserved)
  305.     
  306.     // function prototypes
  307.     blrInitProcPtr            initProc;
  308.     blrGenericProcPtr        terminateProc;
  309.     blrGetCopyrightProcPtr    getCopyrightProc;
  310.     blrRenderProcPtr        renderProc;
  311.     blrClickProcPtr            clickProc;
  312.     blrKeyDownProcPtr        keyDownProc;        // set to nil if you don't want keydowns
  313.     blrErrorProcPtr            errorProc;
  314.     blrGenericProcPtr        settingsProc;        // set to nil if you don't have settings
  315.     blrListenProcPtr        listenProc;            // set to nil if you don't want to receive internal engine messages
  316.     
  317.     blrGetModesProcPtr        getModesProc;        // set to nil if you only have one display mode
  318.     blrGetModeNameProcPtr    getModeNameProc;    // set to nil if you dont use display mode names
  319.     
  320.     // Set these to nil. They are reserved for future expansion so BLRs don't have to be recompiled.
  321.     blrGenericProcPtr        reservedProc1;
  322.     blrGenericProcPtr        reservedProc2;
  323.         
  324.     // Special APIs (Set to nil, MACAST will set it to the right value)
  325.     BLRCallbacksPtr            ma;
  326. } BLRInfoBlock, *BLRInfoPtr;
  327. #pragma options align=reset
  328.  
  329. // useful macros to quickly set headers/footers of VPInfoBlock
  330. #define BLR_INFOBLOCK_HEADER(a,b) BLR_API_VERSION, plugBaseLayerRenderer, a, b, nil
  331. #define BLR_INFOBLOCK_FOOTER nil, nil, nil
  332.  
  333. #ifdef __cplusplus
  334. }
  335. #endif
  336.